﻿/*!
 * 定义模块 Creating (发送通知) 中所有功能的服务 API。
 * 
 * Copyright (c), 上海沃恩信息科技有限公司.
 * All rights reserved.
 * Licensed under BSD (https://www.pittypat.work/bsd.html).
 */

/*
 * @param {Object} $    jQuery 命名空间。
 * @param {Object} $$   pittypat 命名空间。
 * @param {Object} _mod 模块 Creating (发送通知) 的命名空间。
 * 
 * 更多说明请参见：
 * https://www.pittypat.work/com/waln/pittypat/coding/help/_api.js.html。
 */
(function ($, $$, _mod) {
    'use strict';

    // 模块的 API 和 UI 命名空间
    var _api = _mod.api = _mod.api || {};

	/*
	 * 功能 Send (发送通知) 的服务 API。
	 * 
	 * 输入(args):
	 * {
	 *     // 接收人 Id 的列表
	 *     // 接收人 Id 的列表，多个之间使用 ',' 分隔。
	 *     receivers: {string(20000)?},
	 * 
	 *     // 紧急程度
	 *     // 通知的紧急程度代码：1-常规，2-紧急，4-特急。默认为常规（1）。
	 *     urgency: {int8?},
	 * 
	 *     // 分组
	 *     // 通知隶属的分组。
	 *     group: {string(30)?},
	 * 
	 *     // 通知标题
	 *     // 通知的标题。
	 *     title: {string(50)?},
	 * 
	 *     // 通知消息摘要
	 *     // 对通知消息正文的摘要信息。
	 *     summary: {string(200)?},
	 * 
	 *     // 通知正文内容
	 *     // 通知的完整正文内容。
	 *     body: {string(200000)?},
	 * 
	 *     // 正文类型代码
	 *     // 消息正文类型代码：1-纯文本，2-HTML。
	 *     bodyType: {int8?},
	 * 
	 *     // 目标功能路径
	 *     // 点击消息时要进入的路径。
	 *     funcUrl: {string(300)?},
	 * 
	 *     // 引用数据的类型
	 *     // 如果此消息来自某业务功能，则可能引用某业务数据，此属性定义业务数据的类型。
	 *     refDataType: {string(64)?},
	 * 
	 *     // 引用数据键值
	 *     // 消息引用数据的键值。
	 *     refDataKey: {string(50)?},
	 * 
	 *     // 附件 Id
	 *     // 通知消息的附件文件的数目。
	 *     attachmentId: {uuid?} 
	 * }
	 * 
	 * 输出(success.result):
	 * // 通知消息数目
	 * // 成功发送的通知消息的数目。
	 * notificationCount: {int32?}
	 */
    _api.send = $$.api({
        // 请求路径
        url: '~/waln/notifying/creating/send',

        // 请求方法：WS|WEBSOCKET、UPLOAD、UPOST|UPLOAD-POST、UWS|UPLOAD-WS、POST 之一
        method: 'POST',

        // 对 args 进行验证
        validate: function (e) {
            if (!e.args) {
                e.message = '没有提供任何参数。';
                return;
            }

            // 验证 receivers (接收人 Id 的列表)
            if (!e.args.receivers) {
                e.message = '没有提供有效的接收人列表。';
                return;
            }

            // 验证 urgency (紧急程度)
            if (!$$.util.is.int(e.args.urgency, 1, 4)) {
                e.message = '没有提供有效的紧急程度。';
                return;
            }
            
            // 验证 title (通知标题)
            if (!e.args.title) {
                e.message = '没有提供有效的通知标题。';
                return;
            }
            
            // 验证 body (通知正文内容)
            if (!e.args.body) {
                e.message = '没有提供有效的通知正文内容。';
                return;
            }

            // 验证 bodyType (正文类型)
            if (!$$.util.is.int(e.args.bodyType, 1, 2)) {
                e.args.bodyType = 1;
            }

            // 空字符串表示通过验证
            e.message = '';
        },

        // 发送给服务器的数据
        data: function (e) {
            e.data = e.args;
        }
    });

	/*
	 * 功能 Upload (上传附件) 的服务 API。
	 * 
	 * 输入(args):
	 * {
	 *     // 文件名称
	 *     // 附件文件的名称，包含扩展名称。
	 *     name: {string(100)?},
	 * 
	 *     // MIME 类型
	 *     // 附件文件的 MIME 类型。
	 *     mime: {string(100)?},
	 * 
	 *     // 附件文件的大小
	 *     // 附件文件的大小，单位：字节。
	 *     size: {int64?},
	 * 
	 *     // 文件路径
	 *     // 附近文件的虚拟路径。
	 *     url: {string(300)?} 
	 * }
	 * 
	 * 输出(success.result):
	 * // 附件
	 * // 已经上传的附件文件信息。
	 * attachment: {
	 *     // Id
	 *     // 附件文件的 Id。
	 *     id: {uuid?},
	 * 
	 *     // 文件名称
	 *     // 附件文件的名称，包含扩展名称。
	 *     name: {string?},
	 * 
	 *     // MIME 类型
	 *     // 附件文件的 MIME 类型。
	 *     mime: {string?},
	 * 
	 *     // 附件文件的大小
	 *     // 附件文件的大小，单位：字节。
	 *     size: {int64?},
	 * 
	 *     // 文件路径
	 *     // 附近文件的虚拟路径。
	 *     url: {string?},
	 * 
	 *     // 上传人的 Id
	 *     // 上传了当前附件文件的用户的 Id。
	 *     uploaderId: {uuid?},
	 * 
	 *     // 上传时间
	 *     // 上传当前附件文件的时间。
	 *     uploadTime: {datetime?} 
	 * }
	 */
    _api.upload = $$.api({
        // 请求路径
        url: '~/waln/notifying/creating/upload',

        // 请求方法：WS|WEBSOCKET、UPLOAD、UPOST|UPLOAD-POST、UWS|UPLOAD-WS、POST 之一
        method: 'UPOST'
    });

	/*
	 * 功能 DeleteAttachment (删除附件) 的服务 API。
	 * 
	 * 输入(args):
	 * {
	 *     // Id
	 *     // 附件文件的 Id。
	 *     id: {uuid?} 
	 * }
	 * 
	 * 输出(success.result):
	 * // 文件路径
	 * // 附近文件的虚拟路径，用于删除物理文件。
	 * url: {string(300)?}
	 */
    _api.deleteAttachment = $$.api({
        // 请求路径
        url: '~/waln/notifying/creating/deleteattachment',

        // 请求方法：WS|WEBSOCKET、UPLOAD、UPOST|UPLOAD-POST、UWS|UPLOAD-WS、POST 之一
        method: 'POST',

        // 对 args 进行验证
        validate: function (e) {
            // 验证 id
            if (!$$.util.is.uuid(e.args)) {
                e.message = '没有提供有效的Id。';
                return;
            }

            // 空字符串表示通过验证
            e.message = '';
        },

        // 发送给服务器的数据
        data: function (e) {
            e.data = {
                // Id
                id: e.args
            };
        }
    });

	/*
	 * 功能 Receivers (接收人列表) 的服务 API。
	 * 
	 * 输入(args):
	 * {
	 *     // 页码
	 *     // 分页查询时的页码，从 1 开始。
	 *     pageIndex: {int64?},
	 * 
	 *     // 页面尺寸
	 *     // 分页查询时每页最多包含的行数，最小值为 1。
	 *     pageSize: {int64?},
	 * 
	 *     // 排序名称
	 *     // 排序列的标识符名称。
	 *     orderName: {string(50)?},
	 * 
	 *     // 排序方向
	 *     // 排序的方向：ASC 或 DESC。
	 *     orderDirection: {string(4)?},
	 * 
	 *     // 接收人名称
	 *     // 按照接收人的名称对接收人列表进行过滤。如果没有提供名称，则认为查询所有的用户，如果系统用户比较多，这可能比较耗时，并且列表会很长，因此应该尽量使用名称对接收人列表进行过滤。
	 *     name: {string(30)?} 
	 * }
	 * 
	 * 输出(success.result):
	 * {
	 *     // 总行数
	 *     // 分页查询时向客户端返回符合条件的总行数，用于分页设置。
	 *     totalRows: {int64?},
	 * 
	 *     // 接收人列表
	 *     // 根据接收人名称搜索到的符合条件的接收人列表。
	 *     list: [{
	 *         // Id
	 *         id: {uuid?},
	 * 
	 *         // 名称
	 *         // 接收人的名称。
	 *         name: {string?},
	 * 
	 *         // 头像路径
	 *         // 接收人头像文件的路径。
	 *         faceUrl: {string?} 
	 *     }, ...]
	 * }
	 */
    _api.receivers = $$.api({
        // 请求路径
        url: '~/waln/notifying/creating/receivers',

        // 请求方法：WS|WEBSOCKET、UPLOAD、UPOST|UPLOAD-POST、UWS|UPLOAD-WS、POST 之一
        method: 'POST',

        // 对 args 进行验证
        validate: function (e) {
            if (!e.args) {
                e.message = '没有提供任何参数。';
                return;
            }

            // 验证 pageIndex (页码)
            if (!$$.util.is.long(e.args.pageIndex, 1, Long.MAX_VALUE)) {
                e.args.pageIndex = 1; // 默认页码 1
            }

            // 验证 pageSize (页面尺寸)
            if (!$$.util.is.long(e.args.pageSize, 1, 1000)) {
                e.args.pageSize = 8; // 默认页面尺寸 20
            }

            // 验证 orderName (排序名称)
            if (!$$.util.is.identifier(e.args.orderName)) {
                e.args.orderName = 'name'; // 默认排序名称
            }

            // 验证 orderDirection (排序方向)
            if (!$$.util.is.orderDirection(e.args.orderDirection)) {
                e.args.orderDirection = 'asc'; // 默认排序方向
            }
            
            // 空字符串表示通过验证
            e.message = '';
        },

        // 发送给服务器的数据
        data: function (e) {
            e.data = e.args;
        }
    });
})(jQuery, pittypat, pittypat.namespace('waln.notifying.creating'));
